<?php
/*
 * Copyright (c) 2013 Eugene Kuzmenko
 *
 * Permission  is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in  the Software without restriction, including without limitation the rights
 * to  use,  copy,  modify,  merge, publish, distribute, sublicense, and/or sell
 * copies  of  the  Software,  and  to  permit  persons  to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The  above  copyright  notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE  SOFTWARE  IS  PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED,  INCLUDING  BUT  NOT  LIMITED  TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS  FOR  A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS  OR  COPYRIGHT  HOLDERS  BE  LIABLE  FOR  ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 *
 * For more information, see <http://www.aljey.com>.
 */

namespace Al\Core\Lib;

/**
 * A class which can be used to create array-like objects with isset, unset,
 * key, current, push, count, foreach capabilities.
 *
 * @author Eugene Kuzmenko <mail@aljey.com>
 */
class ParameterHolder implements \ArrayAccess, \Iterator, \Countable {

  /**
   * @var array The actual data on which the instance is to operate.
   */
  protected $data = array();

  /**
   * @var mixed The key of the current value.
   */
  protected $position;

  /**
   * Populates the object with an initial set of data and sets the current
   * position value.
   *
   * @param array $data An initial set of data.
   */
  public function __construct($data = array()) {
    $this->data = (array)$data;
    $this->position = key($this->data);
  }

  /**
   * Called whenever someone tries to count($obj).
   *
   * @return int The number of items in the collection.
   */
  public function count() {
    return count($this->data);
  }

  /**
   * Called whenever someone tries to current($obj).
   *
   * @return mixed An array value.
   */
  public function &current() {
    return $this->offsetGet($this->position);
  }

  /**
   * Called whenever someone tries to key($obj).
   *
   * @return mixed An array key.
   */
  public function key() {
    return $this->position;
  }

  /**
   * Called whenever someone tries to next($obj).
   */
  public function next() {
    next($this->data);
    $this->position = key($this->data);
  }

  /**
   * Called whenever someone tries to isset($obj[$offset]).
   *
   * @param mixed $offset An array key.
   * @return boolean Is the key present in the collection?
   */
  public function offsetExists($offset) {
    return array_key_exists($offset, $this->data);
  }

  /**
   * Called whenever someone tries to $obj[$offset].
   *
   * @param mixed $offset An array key.
   * @return mixed The requested value.
   */
  public function &offsetGet($offset) {
    $resp = null;
    if ($this->offsetExists($offset)) $resp = &$this->data[$offset];
    return $resp;
  }

  /**
   * Called whenever someone tries to $obj[$offset] = 5; or $obj[] = 5;
   *
   * @param mixed $offset An array key.
   * @param mixed $value An array value.
   */
  public function offsetSet($offset, $value) {
    $empty = !count($this->data);
    if (is_null($offset)) {
      $this->data[] = $value;
    } else {
      $this->data[$offset] = $value;
    }
    if ($empty) $this->rewind();
  }

  /**
   * Called whenever someone tries to unset($obj[$offset]).
   *
   * @param mixed $offset An array key.
   */
  public function offsetUnset($offset) {
    unset($this->data[$offset]);
    if (count($this->data)) {
      if ($offset === $this->position) $this->rewind();
    } else {
      $this->position = null;
    }
  }

  /**
   * Called whenever someone tries to reset($obj).
   */
  public function rewind() {
    reset($this->data);
    $this->position = key($this->data);
  }

  /**
   * Set the position to the last element.
   */
  public function end() {
    end($this->data);
    $this->position = key($this->data);
  }

  /**
   * Checks the position parameter is still in sync with the underlying data.
   *
   * @return boolean Is the key at the current position present in the
   *                 collection?
   */
  public function valid() {
    return $this->offsetExists($this->position);
  }

}